<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>Overview</title><link rel="stylesheet" href="style/documentation.css" type="text/css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.75.2"><link rel="home" href="index.html" title="JAXB Release Documentation"><link rel="up" href="index.html" title="JAXB Release Documentation"><link rel="prev" href="index.html" title="JAXB Release Documentation"><link rel="next" href="ch02.html" title="Release Notes"><script xmlns:fo="http://www.w3.org/1999/XSL/Format" type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-2105126-1']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
</script></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Overview</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a>&nbsp;</td><th width="60%" align="center">&nbsp;</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ch02.html">Next</a></td></tr></table><hr></div><small xmlns:fo="http://www.w3.org/1999/XSL/Format" class="small">Links: <a href="index.html">Table of Contents</a> | <a href="release-documentation.html">Single HTML</a> | <a href="release-documentation.pdf">Single PDF</a></small><div lang="en" class="chapter" title="Overview" id="jaxb-2-0-overview"><div class="titlepage"><div><div><h2 class="title">Overview</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="ch01.html#documentation">1. Documentation</a></span></dt><dt><span class="section"><a href="ch01.html#license">2. Software Licenses</a></span></dt><dt><span class="section"><a href="ch01.html#jaxb-2-0-sample-apps">3. Sample Apps</a></span></dt><dd><dl><dt><span class="section"><a href="ch01.html#section-3589085759105448">3.1. Using the Runtime Binding Framework</a></span></dt></dl></dd></dl></div><p>The <span class="trademark">Java</span>&#8482; Architecture for XML Binding (JAXB)
    provides an API and tools that automate the mapping between XML documents
    and Java objects.</p><p>The JAXB framework enables developers to perform the following
    operations:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="bold"><strong>Unmarshal</strong></span> XML content into
            a Java representation</p></li><li class="listitem"><p><span class="bold"><strong>Access</strong></span> and <span class="bold"><strong>update</strong></span> the Java representation</p></li><li class="listitem"><p><span class="bold"><strong>Marshal</strong></span> the Java
            representation of the XML content into XML content</p></li></ul></div><p>JAXB gives Java developers an efficient and standard way of mapping
    between XML and Java code. Java developers using JAXB are more productive
    because they can write less code themselves and do not have to be experts
    in XML. JAXB makes it easier for developers to extend their applications
    with XML and Web Services technologies.</p><div class="section" title="1.&nbsp;Documentation"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="documentation">1.&nbsp;Documentation</h2></div></div></div><p>Documentation for this release consists of the following:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="xref" href="ch02.html" title="Release Notes"><i>Release Notes</i></a></p></li><li class="listitem"><p>Running the binding compiler (XJC): [<a class="xref" href="ch04.html#tools-xjc" title="1.&nbsp;XJC">XJC</a>, <a class="xref" href="ch04.html#tools-xjc-ant-task" title="2.&nbsp;XJC Ant Task">XJC Ant Task</a>]</p></li><li class="listitem"><p>Running the schema generator (schemagen): [<a class="xref" href="ch04.html#tools-schemagen" title="3.&nbsp;SchemaGen">SchemaGen</a>, <a class="xref" href="ch04.html#tools-schemagen-ant-task" title="4.&nbsp;SchemaGen Ant Task">SchemaGen Ant Task</a>]</p></li><li class="listitem"><p><a class="xref" href="ch03.html" title="JAXB Users Guide"><i>JAXB Users Guide</i></a></p></li><li class="listitem"><p><a class="link" href="../../nonav/docs/api/jaxb-2-0-overview" target="_top">Javadoc
                API documentation (javax.xml.bind.*)</a></p></li><li class="listitem"><p><a class="xref" href="ch01.html#jaxb-2-0-sample-apps" title="3.&nbsp;Sample Apps">Sample Apps</a></p></li><li class="listitem"><p>JAXB FAQs [<a class="xref" href="ch06.html" title="Frequently Asked Questions"><i>Frequently Asked Questions</i></a>, <a class="link" href="http://java.sun.com/xml/jaxb/faq.html" target="_top">java.sun.com</a>]</p></li></ul></div></div><div class="section" title="2.&nbsp;Software Licenses"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="license">2.&nbsp;Software Licenses</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>2013 Oracle Corporation
                and/or its affiliates. All rights reserved.</p></li><li class="listitem"><p>The JAXB RI 2.2.7 Release is covered
                by <a class="link" href="license.txt" target="_top">the dual license between
                Common Development and Distribution License (CDDL) and GNU
                Public License v2 + classpath exception</a></p></li><li class="listitem"><p>Additional copyright notices and license terms
                applicable to portions of the software are set forth in the
                <a class="link" href="ThirdPartyLicenseReadme.txt" target="_top">3rd Party
                License README</a></p></li></ul></div></div><div lang="en" class="section" title="3.&nbsp;Sample Apps"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="jaxb-2-0-sample-apps">3.&nbsp;Sample Apps</h2></div></div></div><p>This page summarizes basic use-cases for Java-2-Schema,
    Schema-2-Java, and lists all of the sample applications that ship with
    JAXB.</p><div class="section" title="3.1.&nbsp;Using the Runtime Binding Framework"><div class="titlepage"><div><div><h3 class="title" id="section-3589085759105448">3.1.&nbsp;Using the Runtime Binding Framework</h3></div></div></div><div class="section" title="3.1.1.&nbsp;Schema-2-Java"><div class="titlepage"><div><div><h4 class="title" id="section-527832527889161">3.1.1.&nbsp;Schema-2-Java</h4></div></div></div><p>Schema-2-Java is the process of compiling one or more schema
            files into generated Java classes. Here are some of the basic
            steps for developing an app:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Develop/locate your schema</p></li><li class="listitem"><p>Annotate the schema with binding customizations if
                    necessary (or place them in an external bindings
                    file)</p></li><li class="listitem"><p>Compile the schema with the XJC binding
                    compiler</p></li><li class="listitem"><p>Develop your JAXB client application using the Java
                    content classes generated by the XJC binding compiler
                    along with the <code class="literal">javax.xml.bind</code> runtime
                    framework</p></li><li class="listitem"><p>Set your <code class="literal">CLASSPATH</code> to include all
                    of the <a class="xref" href="ch02.html#jars" title="2.&nbsp;Identifying the JAR Files">Identifying the JAR Files</a></p></li><li class="listitem"><p>Compile all of your Java sources with
                    <code class="literal">javac</code></p></li><li class="listitem"><p>Run it!</p></li></ol></div></div><div class="section" title="3.1.2.&nbsp;Java-2-Schema"><div class="titlepage"><div><div><h4 class="title" id="section-308004238994006">3.1.2.&nbsp;Java-2-Schema</h4></div></div></div><p>Java-2-Schema is the process of augmenting existing Java
            classes with the annotations defined in the
            <code class="literal">javax.xml.bind.annotation</code> package so that the JAXB
            runtime binding framework is capable of performing the (un)marshal
            operations. Here are the basic steps for developing an app:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Develop your data model in Java</p></li><li class="listitem"><p>Apply the <code class="literal">javax.xml.bind.annotation</code>
                    annotations to control the binding process</p></li><li class="listitem"><p>Set your <code class="literal">CLASSPATH</code> to include all
                    of the <a class="xref" href="ch02.html#jars" title="2.&nbsp;Identifying the JAR Files">Identifying the JAR Files</a></p></li><li class="listitem"><p>Compile your data model with
                    <code class="literal">javac</code></p><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>Make sure that you <code class="literal">CLASSPATH</code>
                        includes <code class="filename">jaxb-xjc.jar</code> before
                        running <span class="command"><strong>javac</strong></span>.</p></div></li><li class="listitem"><p>The resulting class files will contain your
                    annotations as well other default annotations needed by
                    the JAXB runtime binding framework</p></li><li class="listitem"><p>Develop your client application that uses the data
                    model and develop the code that uses the JAXB runtime
                    binding framework to persist your data model using the
                    (un)marshal operations.</p></li><li class="listitem"><p>Compile and run your client application!</p></li></ol></div><p>For more information about this process, see the the <a class="link" href="http://java.sun.com/webservices/tutorial.html" target="_top">Java
            WSDP Tutorial</a> and the extensive <a class="xref" href="ch01.html#jaxb-2-0-sample-apps" title="3.&nbsp;Sample Apps">Sample Apps</a>
            documentation.</p></div><div class="section" title="3.1.3.&nbsp;Building and Running the Sample Apps with Ant"><div class="titlepage"><div><div><h4 class="title" id="section-3999932384958513">3.1.3.&nbsp;Building and Running the Sample Apps with Ant</h4></div></div></div><p>To run the sample applications, just go into each sample
            directory, and run <span class="command"><strong>ant</strong></span> without any
            option.</p><p>A few sample applications do <span class="emphasis"><em>not</em></span> use
            Ant. For those samples, refer to the included
            <code class="filename">readme.txt</code> files for instructions.</p></div><div class="section" title="3.1.4.&nbsp;List of Sample Apps"><div class="titlepage"><div><div><h4 class="title" id="samples">3.1.4.&nbsp;List of Sample Apps</h4></div></div></div><div class="variablelist"><dl><dt><span class="term"><a class="link" href="../samples/catalog-resolver" target="_top"><span class="application">catalog
                    resolver</span></a></span></dt><dd><p>This example demonstrates how to use the
                        <code class="option">-catalog</code> compiler switch to handle
                        references to schemas in external web sites.</p></dd><dt><span class="term"><a class="link" href="../samples/character-escape" target="_top"><span class="application">character-escape</span></a></span></dt><dd><p>This example shows how you can use the new JAXB
                        RI <code class="literal">Marshaller</code> property
                        <code class="literal">com.sun.xml.bind.characterEscapeHandler</code>
                        to change the default character escaping
                        behavior.</p></dd><dt><span class="term"><a class="link" href="../samples/class-resolver" target="_top"><span class="application">ClassResolver</span></a></span></dt><dd><p>This little DI-container-by-JAXB example
                        demonstrates how one can avoid passing in a list of
                        classes upfront, and instead load classes
                        lazily.</p></dd><dt><span class="term"><a class="link" href="../samples/create-marshal" target="_top"><span class="application">create-marshal
                    (formerly SampleApp3)</span></a></span></dt><dd><p>This sample application demonstrates how to use
                        the <code class="literal">ObjectFactory</code> class to create a
                        Java content tree from scratch and marshal it to XML
                        data. It also demonstrates how to add content to a
                        JAXB List property.</p></dd><dt><span class="term"><a class="link" href="../samples/cycle-recovery" target="_top"><span class="application">Application-driven
                    cycle handling</span></a></span></dt><dd><p>JAXB RI's vendor extension
                        <code class="literal">CycleRecoverable</code> provides
                        application a hook to handle cycles in the object
                        graph. Advanced.</p></dd><dt><span class="term"><a class="link" href="../samples/datatypeconverter" target="_top"><span class="application">datatypeconverter
                    (formerly SampleApp7)</span></a></span></dt><dd><p>This sample application is very similar to the
                        inline-customize sample application (formerly
                        <span class="application">SampleApp6</span>), but
                        illustrates an easier, but not as robust,
                        <code class="literal">&lt;jaxb:javaType&gt;</code>
                        customization.</p></dd><dt><span class="term"><a class="link" href="../samples/dtd" target="_top"><span class="application">dtd</span></a></span></dt><dd><p>This sample application illustrate some of the
                        DTD support available in the JAXB RI's extension mode.
                        Please refer to the <a class="xref" href="ch05.html" title="JAXB RI Extensions"><i>JAXB RI Extensions</i></a> page for more
                        detail.</p></dd><dt><span class="term"><a class="link" href="../samples/element-substitution" target="_top"><span class="application">element-substitution</span></a></span></dt><dd><p>This sample application illustrates how W3C XML
                        Schema substitution groups are supported in JAXB RI's
                        extension mode. Please refer to the <a class="xref" href="ch05.html" title="JAXB RI Extensions"><i>JAXB RI Extensions</i></a> page for more
                        detail.</p></dd><dt><span class="term"><a class="link" href="../samples/external-customize" target="_top"><span class="application">external-customize
                    (formerly SampleApp8)</span></a></span></dt><dd><p>This sample application is identical to the
                        <span class="application">datatypeconverter</span> sample
                        application (formerly
                        <span class="application">SampleApp7</span>) except that the
                        binding customizations are contained in an external
                        binding file.</p></dd><dt><span class="term"><a class="link" href="../samples/fix-collides" target="_top"><span class="application">fix-collides
                    (formerly part of SampleApp9)</span></a></span></dt><dd><p>Another binding customization example that
                        illustrates how to resolve name conflicts. Running
                        this sample without the binding file will result in
                        name collisions (see <code class="filename">readme.txt</code>)
                        . Running <span class="application">ant</span> will use the
                        binding customizations to resolve the name conflicts
                        while compiling the schema.</p></dd><dt><span class="term"><a class="link" href="../samples/inline-customize" target="_top"><span class="application">inline-customize
                    (formerly SampleApp6)</span></a></span></dt><dd><p>This sample application demonstrates how to
                        customize the default binding produced by the XJC
                        binding compiler.</p></dd><dt><span class="term"><a class="link" href="../samples/j2s-create-marshal" target="_top"><span class="application">Java
                    to Schema Binding</span></a></span></dt><dd><p>This sample application demonstrates
                        marshalling, unmarshalling and unmarshal validation
                        with existing Java classes annotated with JAXB
                        annotations.</p></dd><dt><span class="term"><a class="link" href="../samples/j2s-xmlAccessorOrder" target="_top"><span class="application">Ordering
                    Properties and Fieldes in Java to Schema
                    Bindings</span></a></span></dt><dd><p>This sample application demonstrates the use of
                        mapping annotations
                        <code class="literal">@XmlAccessorOrder</code> and
                        <code class="literal">@XmlType.propOrder</code> in Java classes
                        for ordering properties and fields in Java to schema
                        bindings.</p></dd><dt><span class="term"><a class="link" href="../samples/j2s-xmlAdapter" target="_top"><span class="application">Adapters
                    for custom marshaling/unmarshaling XML
                    content</span></a></span></dt><dd><p>This sample application demonstrates the use of
                        interface <code class="literal">XmlAdapter</code> and annotation
                        <code class="literal">XmlJavaTypeAdapter</code> for custom
                        marshaling/unmarshaling XML content into/out of a Java
                        type.</p></dd><dt><span class="term"><a class="link" href="../samples/j2s-xmlAttribute" target="_top"><code class="literal">@XmlAttribute</code>
                    used to define properties and fields as XML Attributes
                    </a></span></dt><dd><p>This sample application demonstrates the use of
                        annotation <code class="literal">@XmlAttribute</code> for
                        defining Java properties and fields as XML
                        attributes.</p></dd><dt><span class="term"><a class="link" href="../samples/j2s-xmlRootElement" target="_top"><span class="application">Defining
                    XML elements via
                    <code class="literal">@XmlRootElement</code></span></a></span></dt><dd><p>This sample application demonstrates the use of
                        annotation <code class="literal">@XmlRootElement</code> to
                        define a class to be an XML element.</p></dd><dt><span class="term"><a class="link" href="../samples/j2s-xmlSchemaType" target="_top">Annotation
                    <code class="literal">@XmlSchemaType</code> is used to customize the
                    mapping of a property or field to an XML built-in type.
                    </a></span></dt><dd><p>This sample application demonstrates the use of
                        annotation <code class="literal">@XmlSchemaType</code> to
                        customize the mapping of a property or field to an XML
                        built-in type.</p></dd><dt><span class="term"><a class="link" href="../samples/j2s-xmlType" target="_top"><span class="application">Ordering
                    Properties and Fieldes in Java to Schema
                    Bindings</span></a></span></dt><dd><p>This sample application demonstrates the use of
                        mapping annotations
                        <code class="literal">@XmlAccessorOrder</code> and
                        <code class="literal">@XmlType.propOrder</code> in Java classes
                        for ordering properties and fields in Java to schema
                        bindings.</p></dd><dt><span class="term"><a class="link" href="../samples/locator-support" target="_top"><span class="application">locator-support</span></a></span></dt><dd><p>This sample shows how to use the new
                        non-standard locator support. By following the
                        instructions in the readme.txt file, you can cause all
                        of the generated impl classes to implement a new
                        interface that provides more information about error
                        locations. When a <code class="literal">ValidationEvent</code>
                        happens on your content tree, simply retrieve the
                        object and cast it down to
                        <code class="literal">com.sun.xml.bind.extra.Locatable</code>.</p></dd><dt><span class="term"><a class="link" href="../samples/modify-marshal" target="_top"><span class="application">modify-marshal
                    (formerly SampleApp2)</span></a></span></dt><dd><p>This sample application demonstrates how to
                        modify a java content tree and marshal it back to XML
                        data.</p></dd><dt><span class="term"><a class="link" href="../samples/namespace-prefix" target="_top"><span class="application">namespace-prefix</span></a></span></dt><dd><p>This sample application demonstrates how to use
                        the new JAXB RI Marshaller property
                        <code class="literal">com.sun.xml.bind.namespacePrefixMapper</code>
                        to customize the namespace prefixes generated during
                        marshalling.</p></dd><dt><span class="term"><a class="link" href="../samples/partial-unmarshalling" target="_top"><span class="application">partial-unmarshalling</span></a></span></dt><dd><p>In this example, the input document will be
                        unmarshalled a small chunk at a time, instead of
                        unmarshalling the whole document at once.</p></dd><dt><span class="term"><a class="link" href="../samples/pull-parser" target="_top"><span class="application">pull
                    parser based unmarshalling</span></a></span></dt><dd><p>This sample app demonstrates how a pull-parser
                        can be used with JAXB to increase the flexibility of
                        processing.</p></dd><dt><span class="term"><a class="link" href="../samples/streaming-unmarshalling" target="_top"><span class="application">Streaming
                    Unmarshalling w/o StAX</span></a></span></dt><dd><p>This example illustrates a different approach to
                        the streaming unmarshalling, which is suitable for
                        processing a large document.</p></dd><dt><span class="term"><a class="link" href="../samples/synchronized-methods" target="_top"><span class="application">Generating
                    synchronized methods</span></a></span></dt><dd><p>This sample shows how to use the new
                        non-standard synchronized method support. By following
                        the instructions in the
                        <code class="filename">readme.txt</code>, you can cause all of
                        the generated impl class methods signatures to contain
                        the <code class="literal">synchronized</code> keyword.</p></dd><dt><span class="term"><a class="link" href="../samples/type-substitution" target="_top"><span class="application">Type
                    substitutoin support</span></a></span></dt><dd><p>This sample app demonstrates type substitution
                        using the W3C XML Schema Part 0: Primer international
                        purchase order schema.</p></dd><dt><span class="term"><a class="link" href="../samples/ubl" target="_top"><span class="application">Universal
                    Business Language (UBL)</span></a></span></dt><dd><p>This project processes a UBL (Universal Business
                        Language) order instance and prints a report to the
                        screen.</p></dd><dt><span class="term"><a class="link" href="../samples/unmarshal-read" target="_top"><span class="application">Using
                    unmarshaller (formerly
                    SampleApp1)</span></a></span></dt><dd><p>This sample application demonstrates how to
                        unmarshal an instance document into a Java content
                        tree and access data contained within it.</p></dd><dt><span class="term"><a class="link" href="../samples/unmarshal-validate" target="_top"><span class="application">validating
                    unmarshaller (formerly
                    SampleApp4)</span></a></span></dt><dd><p>This sample application demonstrates how to
                        enable validation during the unmarshal
                        operations.</p></dd><dt><span class="term"><a class="link" href="../samples/updateablePartialBind" target="_top"><span class="application">Updateable
                    Partial Binding using Binder</span></a></span></dt><dd><p>This sample application demonstrates how to
                        partially map a DOM tree to JAXB (using JAXP 1.3
                        XPath), modify JAXB mapped instance and then update
                        modifications back to the DOM tree.</p></dd><dt><span class="term"><a class="link" href="../samples/vendor-extensions" target="_top"><span class="application">RI-specific
                    customizations</span></a></span></dt><dd><p>This example demonstrates how to use
                        <code class="literal">&lt;xjc:superClass&gt;</code> vendor
                        extensions provided by Sun's JAXB RI, as well as
                        <code class="literal">&lt;jaxb:serializable&gt;</code>
                        customization.</p></dd><dt><span class="term"><a class="link" href="../samples/xml-channel" target="_top"><span class="application">XML
                    message passing via socket</span></a></span></dt><dd><p>This example demonstrates how one can use one
                        communication channel (such as a socket) to send
                        multiple XML messages, and how it can be combined with
                        JAXB.</p></dd><dt><span class="term"><a class="link" href="../samples/xml-stylesheet" target="_top"><span class="application">Marshalling
                    output customization</span></a></span></dt><dd><p>A common customization need for the marshalling
                        output is about introducing extra processing
                        instruction and/or <code class="literal">DOCTYPE</code>
                        declaration. This example demonstrates how such
                        modification can be done easily.</p></dd></dl></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html">Prev</a>&nbsp;</td><td width="20%" align="center">&nbsp;</td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">JAXB Release Documentation&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Release Notes</td></tr></table></div></body></html>